yaml

What is yaml?

The 'yaml' npm package is a JavaScript library for parsing and serializing YAML, a human-friendly data serialization standard. It can be used to convert YAML to JSON and vice versa, and to work with YAML content programmatically in JavaScript.

What are yaml's main functionalities?

Parsing YAML to JSON

This feature allows you to parse a string of YAML content and convert it into a JavaScript object.

const yaml = require('yaml');
const yamlText = 'key: value\nnumber: 123';
const jsonObject = yaml.parse(yamlText);
console.log(jsonObject);

Stringifying JSON to YAML

This feature enables you to take a JavaScript object and serialize it into a YAML formatted string.

const yaml = require('yaml');
const jsonObject = { key: 'value', number: 123 };
const yamlText = yaml.stringify(jsonObject);
console.log(yamlText);

Custom Tags

This feature allows you to define custom tags for specialized YAML types, enabling the parsing of YAML content with custom data structures.

const yaml = require('yaml');
const customType = { identify: value => value instanceof Set, tag: 'tag:yaml.org,2002:set', resolve: (doc, cst) => new Set(cst.strValue.split(', ')) };
yaml.defaultOptions.customTags = [customType];
const yamlText = '!!set a, b, c';
const data = yaml.parse(yamlText);
console.log(data);

Other packages similar to yaml

js-yaml

js-yaml is another popular YAML parser and serializer for JavaScript. It offers similar functionality to the 'yaml' package, including parsing and stringifying, and it also provides a safe loading option to prevent executing arbitrary code during parsing.

yamljs

yamljs is a YAML parser and dumper written in JavaScript. It provides functionality similar to 'yaml' and 'js-yaml' but has a different API design and may have different performance characteristics.

README

YAML

yaml is a JavaScript parser and stringifier for YAML, a human friendly data serialization standard. It supports both parsing and stringifying data using all versions of YAML, along with all common data schemas. As a particularly distinguishing feature, yaml fully supports reading and writing comments and blank lines in YAML documents.

The library is released under the ISC open source license, and the code is available on GitHub. It has no external dependencies and runs on Node.js 6 and later, and in browsers from IE 11 upwards.

For the purposes of versioning, any changes that break any of the endpoints or APIs documented here will be considered semver-major breaking changes. Undocumented library internals may change between minor versions, and previous APIs may be deprecated (but not removed).

For more information, see the project's documentation site: eemeli.org/yaml/v1

To install:

npm install yaml

Note: This is yaml@1. You may also be interested in the next version, currently available as yaml@next.

API Overview

The API provided by yaml has three layers, depending on how deep you need to go: Parse & Stringify, Documents, and the CST Parser. The first has the simplest API and "just works", the second gets you all the bells and whistles supported by the library along with a decent AST, and the third is the closest to YAML source, making it fast, raw, and crude.

import YAML from 'yaml'
// or
const YAML = require('yaml')

Parse & Stringify

• YAML.parse(str, options): value
• YAML.stringify(value, options): string

YAML Documents

• YAML.createNode(value, wrapScalars, tag): Node
• YAML.defaultOptions
• YAML.Document
  • constructor(options)
  • defaults
  • #anchors
  • #contents
  • #errors
• YAML.parseAllDocuments(str, options): YAML.Document[]
• YAML.parseDocument(str, options): YAML.Document

import { Pair, YAMLMap, YAMLSeq } from 'yaml/types'

• new Pair(key, value)
• new YAMLMap()
• new YAMLSeq()

CST Parser

import parseCST from 'yaml/parse-cst'

• parseCST(str): CSTDocument[]
• YAML.parseCST(str): CSTDocument[]

YAML.parse

# file.yml
YAML:
  - A human-readable data serialization language
  - https://en.wikipedia.org/wiki/YAML
yaml:
  - A complete JavaScript implementation
  - https://www.npmjs.com/package/yaml

import fs from 'fs'
import YAML from 'yaml'

YAML.parse('3.14159')
// 3.14159

YAML.parse('[ true, false, maybe, null ]\n')
// [ true, false, 'maybe', null ]

const file = fs.readFileSync('./file.yml', 'utf8')
YAML.parse(file)
// { YAML:
//   [ 'A human-readable data serialization language',
//     'https://en.wikipedia.org/wiki/YAML' ],
//   yaml:
//   [ 'A complete JavaScript implementation',
//     'https://www.npmjs.com/package/yaml' ] }

YAML.stringify

import YAML from 'yaml'

YAML.stringify(3.14159)
// '3.14159\n'

YAML.stringify([true, false, 'maybe', null])
// `- true
// - false
// - maybe
// - null
// `

YAML.stringify({ number: 3, plain: 'string', block: 'two\nlines\n' })
// `number: 3
// plain: string
// block: >
//   two
//
//   lines
// `

---

Browser testing provided by: